Breaking change

This is a major rewrite of livekit-plugins-slng. We would like it released as 2.0.0 (please bump accordingly at release time; version.py is left untouched per contribution guidelines).

What changed

The plugin now connects exclusively through SLNG's Unmute Bridge, the gateway's normalized protocol layer. A model identifier is all that is needed (slng.STT(model="deepgram/nova:3")); the plugin builds the bridge WebSocket endpoint itself.

• Bridge-only routing. The 1.x model_endpoint / model_endpoints parameters were removed and now raise a clear ValueError pointing at the replacement (model= or connections=[...]). STT no longer defaults to a model; a model or connections must be passed explicitly.
• Failover chains for STT and TTS. connections=[...] accepts model identifiers, bridge endpoint URLs, or typed STTConnectionConfig / TTSConnectionConfig objects. STT fails over at safe stream boundaries and replays buffered audio (including a pending finalize) onto the new connection; TTS fails over only before first audio. HTTP 413 is treated as terminal instead of walking the chain, since every candidate would reject the same oversized payload. Recovery back to the primary is cooldown-based.
• Single-candidate resilience. With no further fallback candidate (the common single-model setup), a transient mid-utterance connection drop or a stalled-finalize watchdog timeout reconnects the same endpoint and replays the buffered audio rather than ending the stream, bounded by max_retry and reset on real transcript progress, so a persistently failing endpoint still surfaces the error.
• Faster end-of-utterance. The stream sends the bridge a finalize signal when the agent's user state transitions to listening; wire it with stt.attach_to_session(session) (or call stt.notify_user_state(...) from a user_state_changed handler). A watchdog (final_timeout_s, opt-in) guards against providers that never deliver the final transcript. Interim results no longer disarm the watchdog.
• BYOK support. provider_api_key forwards the customer's own provider credential as the gateway's X-Slng-Provider-Key header.
• Geographic zone routing. In addition to the existing region_override, a new world_part_override constrains routing to a broad geographic zone (maps to the gateway's X-World-Part-Override header; region_override takes precedence). Both propagate to fallback candidates.
• Typed plugin events. slng_event emits structured events for gateway session IDs and fallback attempt / switch / exhaustion.
• Removed implicit behavior. Client-side language and voice normalization are gone by design: values are passed verbatim so they always match the selected model's contract (e.g. Sarvam requires BCP-47 hi-IN). Voice IDs are provider-native.
• Honest capabilities. Only pcm_s16le STT input is accepted (previously other encodings were silently mislabeled), recognize() raises NotImplementedError (the bridge is WebSocket-only), and offline_recognize is reported as False.
• Hardening. Bounded WebSocket receives with the connection timeout (mirroring the Cartesia plugin), lazy-starting fallback streams that support plain async for and collect(), per-run stream state so base-class retries produce audio, consistent watchdog and speech-event state across options-change reconnects, runtime voice/language/speed updates that propagate to fallback candidates and safely invalidate warm-standby connections, a bounded cap on silent reconnects, and no leaked connection or timing state.

Testing

• make check passes: ruff format, ruff lint, and strict mypy via scripts/check_types.py.
• The plugin is validated by an out-of-tree unit suite (scripted fake WebSockets, no network) covering failover with audio + finalize replay, single-candidate reconnect-and-replay on drop and on timeout, options-change reconnect state and event brackets, watchdog behavior, retry-safe stream construction, warm-standby invalidation, fallback stream contracts, phrase batching, geo override propagation, option forwarding, and encoding validation. Test files are not included in this PR (removed on request to keep it focused).
• Verified live against the production SLNG gateway: STT flush-to-final latency, TTS synthesis across ElevenLabs / Cartesia / Deepgram / Rime bridge models, failover chains, BYOK, and world-part override steering (confirmed via gateway routing logs).

Notes for reviewers

• README.md was rewritten to document the 2.0 API, including a "Migrating from 1.x" section.
• END_OF_SPEECH is emitted per final transcript (rather than waiting for provider utterance-end events) deliberately: it preserves the low end-of-utterance latency the finalize flow provides.
• Both synthesize() and the streaming path treat a server close after audio was received as end-of-segment deliberately: several bridge providers (Rime, Cartesia) terminate segments via close.
• Several findings from this PR's automated review were confirmed and fixed in follow-up commits; each fix is covered by a test in our out-of-tree suite.